home *** CD-ROM | disk | FTP | other *** search
/ Visual Basic 5 Developer's Kit / vb5 dev kit.iso / dev / call32 / call32.txt < prev    next >
Encoding:
Text File  |  1996-09-11  |  8.4 KB  |  219 lines
  1. CALL32.DLL: 32-bit DLL calling library for Visual Basic
  2. by Peter Golde 
  3.  
  4. (modified by Rob Lichtefeld 10-Sep-1996)
  5.  
  6. This program is placed in the public domain.
  7. Please feel free to redistribute as you wish.  
  8. No guarantees are made as to its suitability or
  9. usefulness, and no support can be provided [by 
  10. Peter Golde].
  11.  
  12. However, since I modified the .dll and pretty well understand 
  13. how it works I will try to answer questions that arise from 
  14. the use of this .dll.  Also, due to the price charged for the 
  15. .dll, I won't promise anything that takes away from my paying job.  
  16. I must thank Peter Golde for coming up with the original.
  17.  
  18. You are welcome to contact me at:
  19.  
  20. Compuserve: 74431,240  (either by Mail or in the VBPJForum)
  21.   Internet: 74431.240@compuserve.com
  22.                  ^ note the period instead of the comma
  23.  
  24. Rob Lichtefeld
  25. Spalding Software, Inc.
  26. 154 Technology Parkway
  27. Suite 250
  28. Norcross, GA 30092 USA
  29.  
  30.  
  31. 1. Summary
  32. ----------
  33.  
  34. CALL32.DLL is a DLL that can be used for calling routines in 32-bit
  35. DLLs on Windows NT and Windows95.  It may or may not work on other 
  36. 32-bit operating systems.  
  37.  
  38. Using it, a Visual Basic program, running in the Win16 subsystem, 
  39. can declare and call functions in any 32-bit DLL (including, but not 
  40. limited to, the system DLLs).  CALL32.DLL works on both the x86 and 
  41. MIPS versions on NT.  It has not been tested on Alpha or other versions, 
  42. but should work.
  43.  
  44.  
  45. 2. Usage
  46. --------
  47.  
  48. To call a function in a 32-bit DLL, follow the following steps:  
  49.  
  50. A) Declare the CALL32 functions as follows (each Declare should be on a 
  51.    single line):
  52.  
  53.    Declare Function Declare32 Lib "call32.dll" (ByVal Func$, ByVal Library$, ByVal Args$) As Long
  54.    Declare Sub FreeCall32IDs Lib "call32.dll" ()
  55.  
  56. B) Next, declare the function(s) you wish to call.  Declare it in the 
  57.    ordinary fashion, with the following exceptions:
  58.  
  59.       - Use a library name of "call32.dll"
  60.       - Use an Alias of "Call32"
  61.       - Add an additional argument at the end, of type ByVal Long
  62.  
  63.    For example, if you are calling the function:
  64.  
  65.       GetWindowText(HWND hwnd, LPSTR lpsz, int cch)
  66.  
  67.    declare it as follows (remember that ints and all handles are 32 bits,
  68.    so use a Long):
  69.  
  70.       Declare Function GetWindowText Lib "call32.dll" Alias "Call32" (ByVal hwnd As Long, ByVal lpsz As String, ByVal cch As Long, ByVal id As Long) As Long
  71.  
  72.  
  73. C) In the initialization section of your application, you declare the
  74.    actual library and name of the function you want to call with 
  75.    the Declare32 function.  Pass it the name of the function, the
  76.    library, and a string describing the argument types.  
  77.    
  78.    Each letter in the string declares the type of one argument, 
  79.    and should be either: 
  80.      "i" for a 32 bit integer or handle type, 
  81.      "p" for any pointer type, or 
  82.      "w" for an HWND parameter you want to pass a 16 bit HWND to and 
  83.          have be automatically converted to a 32 bit HWND.  
  84.  
  85.    The return value of Declare32 should be saved away in 
  86.    a global variable to be passed as the last parameter to the
  87.    function you declared earlier.  So, continue the example, you
  88.    would call:
  89.  
  90.    idGetWindowText = Declare32("GetWindowText", "user32", "wpi")
  91.   
  92.    (As a side note, this would be more properly declared as 
  93.    "GetWindowTextA", since this is the real exported name.  However,
  94.    Declare32 will automatically add an "A" to the end of a 
  95.    function name if necessary).
  96.  
  97.  
  98. D) To call the function, you would just call:
  99.  
  100.    cbCopy = GetWindowText(hwnd, sz, cb, idGetWindowText)   
  101.  
  102.  
  103. E) In the shutdown section of your application, you should call the 
  104.    FreeCall32IDs subroutine to free the libraries that were loaded by 
  105.    the .DLL for your program.  If you do not call this subroutine, the 
  106.    libraries will not be freed.  This causes the counter for the 32-bit 
  107.    DLLs to never be decremented and thus never unloaded from memory.
  108.  
  109.    
  110.    
  111. 3. Data Types and Handles 
  112. -------------------------
  113.  
  114. It is important to use the correct data types when calling DLL
  115. functions.  There are two important points to pay attention
  116. to when using CALL32.DLL.  First, only 32 bit integers can
  117. be passed to a DLL procedures.  Since virtually all 32 bit
  118. functions take int, UINT, LONG, DWORD, or HANDLE parameters,
  119. which are all 32 bits, this is not a major restriction.  However,
  120. you must remember to always declare functions arguments are
  121. Long, and not Integer.
  122.  
  123. Secondly, 16 bit handles and 32 bit handles are not interchangable.
  124. For example, a 16 bit bitmap handle that you get from calling
  125. a 16 bit DLL or from the VB environment cannot be passed to
  126. a 32 bit function expecting a bitmap handle.  Similarly, a 
  127. 32 bit handle gotten from a 32 bit function cannot be passed to a 
  128. 16 bit DLL.  The only exception is window handles (HWND).  If
  129. you declare a function parameter with the "w" letter in the 
  130. argument description string passed to Declare32, the corresponding
  131. parameter will be automatically converted from a 16 bit HWND to
  132. a 32 bit HWND when the call is made.  You must still declare the
  133. argument as a LONG.  This is convenient, for example, when passing
  134. the value returned by the "hWnd" property of a control to a 
  135. 32 bit DLL function.  Only windows created by your application
  136. can be translated.
  137.  
  138. Summary of data types:
  139.  
  140. C data type      Type specified in Declare   Character for Declare32
  141.  
  142. int, UINT          ByVal Long                  i
  143. LONG, DWORD        ByVal Long                  i
  144. HANDLE             ByVal Long                  i
  145. WORD, short        not supported                 
  146. HWND               ByVal Long                  w (i for no 16->32
  147.                                                   translation)
  148. LPSTR              ByVal String                p
  149. LPLONG, LPDWORD,
  150. LPUINT, int FAR *  Long                        p
  151. LPWORD             Integer                     p
  152.  
  153.  
  154. 4. Note on Declare32 function names
  155. -----------------------------------
  156.  
  157. Declare32 will automatically try three different names for
  158. the function name you pass in.  First, it uses the exact
  159. name you pass in.  If that function name isn't found,
  160. it converts the name to the stdcall decorated name convention,
  161. by adding an underscore at the beginning, and adding "@nn" at
  162. the end, where "nn" is the number of bytes of arguments.  If
  163. that name isn't found, it adds an "A" to the end of the original
  164. name to try the Win32 ANSI function calling convention.
  165.  
  166.  
  167. 5. Run-time Error Summary
  168. -------------------------
  169.  
  170. The following run-time errors can be generated by CALL32.DLL
  171.  
  172. 30001   Can't load DLL: "|" (error=|)
  173.    The DLL name passed to Declare32 was not the name of a 
  174.    valid 32 bit DLL. The Win32 error code is specified at the
  175.    end of the error message, this can help determine why
  176.    the DLL didn't load.  
  177.    
  178. 30002   Can't find specified function
  179.    The function name passed to Declare32 could not be found
  180.    in the DLL.
  181.    
  182. 30003   Invalid parameter definition string
  183.    The parameter definition string passed to Declare32 had
  184.    an invalid character in it, or was too long (32 parameters
  185.    is the limit).
  186.    
  187. 30004   Not running on Windows NT
  188.    The program is not running in the Windows16 subsystem of
  189.    Windows NT.
  190.    
  191. 30005   Invalid window handle
  192.    The 16 bit window handle passed as a parameter declared
  193.    with the 'w' character was not a valid 16 bit window handle,
  194.    or refers to a window from a different process.  
  195.  
  196.  
  197. 6.  Change History
  198. ------------------
  199.  
  200. 1.00       Original Version
  201. (8/31/93)    
  202.  
  203. 1.01       Better error message when DLL can't be loaded
  204. (9/27/93)  Stdcall name decoration support
  205.            Source code available
  206.            Sample Bezier program from Adam Rauch
  207.     
  208. 2.00       Fixed problem with running more than 1 VB program calling the
  209. (9/10/96)  .DLL at one time:
  210.            1) Changed memory allocation to set the GMEM_SHARE flag so that 
  211.               the .DLL "owns" the Global memory instead of the first task.
  212.            2) Added the hTask element to the array to track which IDs went 
  213.               with which VB tasks.
  214.            3) Added the FreeCall32IDs subroutine because errors caused by 
  215.               calling FreeLibrary32W() in the WEP procedure.
  216.            4) Fixed the FreeLibrary32W() call in the Declare32 procedure 
  217.               where it was freeing the handle to Kernel and it should have 
  218.               been freeing the handle to Kernel32.
  219.